home *** CD-ROM | disk | FTP | other *** search
/ Aminet 14 / Aminet 14 - Oct 1996.iso / Tools / MUI / Developer / Autodocs / MUI_Notify.doc < prev    next >
Text File  |  1996-08-20  |  23KB  |  823 lines
  1. TABLE OF CONTENTS
  2.  
  3. Notify.mui/Notify.mui
  4. Notify.mui/MUIA_ApplicationObject
  5. Notify.mui/MUIA_AppMessage
  6. Notify.mui/MUIA_HelpLine
  7. Notify.mui/MUIA_HelpNode
  8. Notify.mui/MUIA_NoNotify
  9. Notify.mui/MUIA_ObjectID
  10. Notify.mui/MUIA_Parent
  11. Notify.mui/MUIA_Revision
  12. Notify.mui/MUIA_UserData
  13. Notify.mui/MUIA_Version
  14. Notify.mui/MUIM_CallHook
  15. Notify.mui/MUIM_Export
  16. Notify.mui/MUIM_FindUData
  17. Notify.mui/MUIM_GetConfigItem
  18. Notify.mui/MUIM_GetUData
  19. Notify.mui/MUIM_Import
  20. Notify.mui/MUIM_KillNotify
  21. Notify.mui/MUIM_KillNotifyObj
  22. Notify.mui/MUIM_MultiSet
  23. Notify.mui/MUIM_NoNotifySet
  24. Notify.mui/MUIM_Notify
  25. Notify.mui/MUIM_Set
  26. Notify.mui/MUIM_SetAsString
  27. Notify.mui/MUIM_SetUData
  28. Notify.mui/MUIM_SetUDataOnce
  29. Notify.mui/MUIM_WriteLong
  30. Notify.mui/MUIM_WriteString
  31. Notify.mui/Notify.mui
  32.  
  33.     Notify class is superclass of all other MUI classes.
  34.     It's main purpose is to handle MUI's notification
  35.     mechanism, but it also contains some other methods
  36.     and attributes useful for every object.
  37. Notify.mui/MUIA_ApplicationObject
  38.  
  39.     NAME
  40.     MUIA_ApplicationObject -- (V4 ) [..G], Object *
  41.  
  42.     FUNCTION
  43.     You can obtain a pointer to the application object
  44.     that some gadget belongs to by using this attribute.
  45.     Useful mainly within callback hooks if you do not want
  46.     to deal with global variables.
  47.  
  48.     If your object is not currently attached to an application,
  49.     you will receive NULL.
  50.  
  51.     SEE ALSO
  52.     MUIA_WindowObject
  53. Notify.mui/MUIA_AppMessage
  54.  
  55.     NAME
  56.     MUIA_AppMessage -- (V5 ) [..G], struct AppMessage *
  57.  
  58.     FUNCTION
  59.     When your window is an AppWindow, i.e. you have set the
  60.     MUIA_Window_AppWindow attribute to TRUE, you will be able
  61.     to get AppMessages by listening to MUIA_AppMessage.
  62.     Whenever an AppMessage arrives, this attribute will
  63.     be set to a pointer to that message.
  64.  
  65.     MUIA_AppMessage is object specific. You can e.g. set up
  66.     different notifications for different objects in your window,
  67.     they will only get exectued when icons are dropped over the
  68.     specific object.
  69.  
  70.     If you wait on MUIA_AppMessage with a window object, your
  71.     notify will always get executed when icons are dropped on
  72.     the window.
  73.  
  74.     Notes:
  75.  
  76.     - You should use the MUIM_CallHook method to call a
  77.       hook function when an AppMessage arrives (see below).
  78.       The pointer to the AppMessage is valid only as long as 
  79.       the notification method is executed.
  80.  
  81.     - AppWindows are only possible on the workench screen.
  82.  
  83.  
  84.     EXAMPLE
  85.  
  86.     /* Call the AppMsgHook when an icon is dropped on a listview */
  87.  
  88.     DoMethod(lvobj,MUIM_Notify,MUIA_AppMessage,MUIV_EveryTime,
  89.              lvobj,3,MUIM_CallHook,&AppMsgHook,MUIV_TriggerValue);
  90.  
  91.     /* Call the AppMsgHook when an icon is dropped on the window */
  92.  
  93.     DoMethod(winobj,MUIM_Notify,MUIA_AppMessage,MUIV_EveryTime,
  94.              winobj,3,MUIM_CallHook,&AppMsgHook,MUIV_TriggerValue);
  95.  
  96.     SEE ALSO
  97.     MUIA_Window_AppWindow, MUIA_Application_DropObject, MUIM_CallHook
  98. Notify.mui/MUIA_HelpLine
  99.  
  100.     NAME
  101.     MUIA_HelpLine -- (V4 ) [ISG], LONG
  102.  
  103.     FUNCTION
  104.     Define a line in a help file specified with 
  105.     MUIA_Application_HelpFile.
  106.  
  107.     SEE ALSO
  108.     MUIA_Application_HelpFile, MUIA_HelpNode
  109. Notify.mui/MUIA_HelpNode
  110.  
  111.     NAME
  112.     MUIA_HelpNode -- (V4 ) [ISG], STRPTR
  113.  
  114.     FUNCTION
  115.     Define a node in a help file specified with
  116.     MUIA_Application_HelpFile.
  117.  
  118.     SEE ALSO
  119.     MUIA_Application_HelpFile, MUIA_HelpLine
  120. Notify.mui/MUIA_NoNotify
  121.  
  122.     NAME
  123.     MUIA_NoNotify -- (V7 ) [.S.], BOOL
  124.  
  125.     FUNCTION
  126.     If you set up a notify on an attibute to react on user input,
  127.     you will also recognize events when you change this attribute
  128.     under program control with SetAttrs(). Setting MUIA_NoNotify
  129.     together with your attribute will prevent this notification
  130.     from being triggered.
  131.  
  132.     NOTE
  133.     MUIA_NoNotify is a "one time" attribute. Its only valid during
  134.     the current SetAttrs() call!
  135.  
  136.     EXAMPLE
  137.     SetAttrs(slider,MUIA_NoNotify,TRUE,MUIA_Slider_Level,26,TAG_DONE);
  138. Notify.mui/MUIA_ObjectID
  139.  
  140.     NAME
  141.     MUIA_ObjectID -- (V11) [ISG], ULONG
  142.  
  143.     FUNCTION
  144.     This is a synonym for MUIA_ExportID.
  145.  
  146.     SEE ALSO
  147.     MUIA_ExportID
  148. Notify.mui/MUIA_Parent
  149.  
  150.     NAME
  151.     MUIA_Parent -- (V11) [..G], Object *
  152.  
  153.     FUNCTION
  154.     Get a pointer to the parent object of the current object.
  155.     The parent obect is always the group/family object which 
  156.     contains the current object. If an object has no parent
  157.     group, this attribute will be NULL.
  158.  
  159.     SEE ALSO
  160.     group.mui/MUIA_Group_Child
  161. Notify.mui/MUIA_Revision
  162.  
  163.     NAME
  164.     MUIA_Revision -- (V4 ) [..G], LONG
  165.  
  166.     FUNCTION
  167.     Get the revision number of an objects class. Although
  168.     MUIA_Revision is documented at notify class, you will
  169.     of course receive the revision number of the objects true
  170.     class.
  171.  
  172.     EXAMPLE
  173.     strobj = MUI_NewObject(MUIC_String,...,TAG_DONE);
  174.         ...
  175.     get(strobj,MUIA_Version ,&v);
  176.     get(strobj,MUIA_Revision,&r);
  177.     printf("String class version %ld.%ld\n",v,r);
  178.  
  179.     SEE ALSO
  180.     MUIA_Version
  181. Notify.mui/MUIA_UserData
  182.  
  183.     NAME
  184.     MUIA_UserData -- (V4 ) [ISG], ULONG
  185.  
  186.     FUNCTION
  187.     A general purpose value to fill in any kind of information.
  188. Notify.mui/MUIA_Version
  189.  
  190.     NAME
  191.     MUIA_Version -- (V4 ) [..G], LONG
  192.  
  193.     FUNCTION
  194.     Get the version number of an objects class. Although
  195.     MUIA_Version is documented at notify class, you will
  196.     of course receive the version number of the objects true
  197.     class.
  198.  
  199.     EXAMPLE
  200.     strobj = MUI_NewObject(MUIC_String,...,TAG_DONE);
  201.         ...
  202.     get(strobj,MUIA_Version ,&v);
  203.     get(strobj,MUIA_Revision,&r);
  204.     printf("String class version %ld.%ld\n",v,r);
  205.  
  206.     SEE ALSO
  207.     MUIA_Revision
  208. Notify.mui/MUIM_CallHook
  209.  
  210.     NAME
  211.     MUIM_CallHook (V4 )
  212.  
  213.     SYNOPSIS
  214.     DoMethod(obj,MUIM_CallHook,struct Hook *Hook, ULONG param1, /* ... */);
  215.  
  216.     FUNCTION
  217.     Call a standard amiga callback hook, defined by a Hook
  218.     structure. Together with MUIM_Notify, you can easily
  219.     bind hooks to buttons, your hook will be called when
  220.     the button is pressed.
  221.  
  222.     The hook will be called with a pointer to the hook
  223.     structure in a0, a pointer to the calling object in a2
  224.     and a pointer to the first parameter in a1.
  225.  
  226.     INPUTS
  227.     Hook       pointer to a struct Hook.
  228.     param1,... zero or more parameters. The hook function will
  229.                receive a pointer to the first parameter in
  230.                register a1.
  231.  
  232.     EXAMPLE
  233.  
  234.     standalone:
  235.  
  236.     DoMethod(obj,MUIM_CallHook,&hookstruct,13,42,"foobar","barfoo");
  237.  
  238.     within a notification statement:
  239.  
  240.     DoMethod(propobj,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime,
  241.              propobj,3,MUIM_CallHook,&prophook,MUIV_TriggerValue);
  242.  
  243.     prophook will be called every time the knob is moving and gets
  244.     a pointer to the knobs current level in a1.
  245. Notify.mui/MUIM_Export
  246.  
  247.     NAME
  248.     MUIM_Export (V12)
  249.  
  250.     SYNOPSIS
  251.     DoMethod(obj,MUIM_Export,Object *dataspace);
  252.  
  253.     FUNCTION
  254.     This method is called for each object in the application tree
  255.     (including menus) during execution of MUIM_Application_Save.
  256.     It's purpose is to export an objects "contents" to a dataspace
  257.     object for later saving to an IFF file.
  258.  
  259.     If you override this method to export your custom data, you
  260.     are supposed to use your MUIA_ObjectID as ID for the dataspace
  261.     entry. Don't export if your MUIA_ObjectID is 0.
  262.  
  263.     RESULT
  264.     Return 0 if you dont want your superclasses to be able to
  265.     import/export any values themselves. Otherwise
  266.     return(DoSuperMethodA(cl,obj,msg));
  267.  
  268.     EXAMPLE
  269.     ULONG mExport(struct IClass *cl,Object *obj,struct MUIP_Export *msg)
  270.     {
  271.        struct Data *mydata = INST_DATA(cl,obj);
  272.        ULONG id;
  273.        ULONG exp=0;
  274.  
  275.        if (id=(muiNotifyData(obj)->mnd_ObjectID))
  276.        {
  277.           DoMethod(msg->dataspace,MUIM_Dataspace_Add,
  278.                    &mydata->myvalue,sizeof(LONG),id);
  279.        }
  280.  
  281.        return(0);
  282.     }
  283.  
  284.     SEE ALSO
  285.     MUIM_Import, application.mui/MUIM_Application_Load,
  286.     application.mui/MUIM_Application_Save
  287. Notify.mui/MUIM_FindUData
  288.  
  289.     NAME
  290.     MUIM_FindUData (V8 )
  291.  
  292.     SYNOPSIS
  293.     DoMethod(obj,MUIM_FindUData,ULONG udata);
  294.  
  295.     FUNCTION
  296.     This method tests if the MUIA_UserData of the object
  297.     contains the given <udata> and returns the object
  298.     pointer in this case.
  299.  
  300.     Although this is not very useful for single objects,
  301.     performing this method on objects that handle children
  302.     can become very handy. In this case, all the children
  303.     (any maybe their children) are tested against <udata>
  304.     and the first matching object is returned.
  305.  
  306.     This method is especially useful if you created your
  307.     menu tree with a NewMenu structure and you want to
  308.     find the object pointer for a single menu item.
  309.  
  310.     INPUTS
  311.     udata - userdata to look for.
  312.  
  313.     RESULT
  314.     A pointer to the first object with the specified user data
  315.     or NULL if no object is found.
  316.  
  317.     NOTES
  318.     If you have many objects in your application, MUIM_FindUData
  319.     may take quite long. You can limit the amount of time
  320.     by performing the method not on the application but on the
  321.     window or even on the group/family your object is placed in.
  322.  
  323.     SEE ALSO
  324.     MUIM_GetUData, MUIM_SetUData
  325. Notify.mui/MUIM_GetConfigItem
  326.  
  327.     NAME
  328.     MUIM_GetConfigItem (V11)
  329.  
  330.     SYNOPSIS
  331.     DoMethod(obj,MUIM_GetConfigItem,ULONG id, ULONG *storage);
  332.  
  333.     FUNCTION
  334.     yet undocumented, complain in the beta mailing list :)
  335.  
  336.     INPUTS
  337.  
  338.     RESULT
  339.  
  340.     BUGS
  341.  
  342.     SEE ALSO
  343.  
  344. Notify.mui/MUIM_GetUData
  345.  
  346.     NAME
  347.     MUIM_GetUData (V8 )
  348.  
  349.     SYNOPSIS
  350.     DoMethod(obj,MUIM_GetUData,ULONG udata, ULONG attr, ULONG *storage);
  351.  
  352.    FUNCTION
  353.     This method tests if the MUIA_UserData of the object
  354.     contains the given <udata> and gets <attr> to
  355.     <storage> for itself in this case.
  356.  
  357.     Although this is not very useful for single objects,
  358.     performing this method on objects that handle children
  359.     can become very handy. In this case, all the children
  360.     (any maybe their children) are searched against <udata>
  361.     and the first matching objects will be asked for the
  362.     specified attribute.
  363.  
  364.     INPUTS
  365.     udata   - userdata to look for.
  366.     attr    - attribute to get.
  367.     storage - place to store the attribute.
  368.  
  369.     NOTES
  370.     If you have many objects in your application, MUIM_GetUData
  371.     may take quite long. You can limit the amount of time
  372.     by performing the method not on the application but on the
  373.     window or even on the group/family your objects are place in.
  374.  
  375.     SEE ALSO
  376.     MUIM_SetUData, MUIM_FindUData
  377. Notify.mui/MUIM_Import
  378.  
  379.     NAME
  380.     MUIM_Import (V12)
  381.  
  382.     SYNOPSIS
  383.     DoMethod(obj,MUIM_Import,Object *dataspace);
  384.  
  385.     FUNCTION
  386.     This method is called for each object in the application tree
  387.     (including menus) during execution of MUIM_Application_Load.
  388.     It's purpose is to import an objects "contents" from a dataspace
  389.     object after loading from an IFF file.
  390.  
  391.     If you override this method to import your custom data, you
  392.     are supposed to use your MUIA_ObjectID as ID for the dataspace
  393.     entry. Don't import if your MUIA_ObjectID is 0.
  394.  
  395.     RESULT
  396.     Return 0 if you dont want your superclasses to be able to
  397.     import/export any values themselves. Otherwise
  398.     return(DoSuperMethodA(cl,obj,msg));
  399.  
  400.     EXAMPLE
  401.     ULONG mImport(struct IClass *cl,Object *obj,struct MUIP_Import *msg)
  402.     {
  403.        struct Data *mydata = INST_DATA(cl,obj);
  404.        ULONG id;
  405.        ULONG *data;
  406.  
  407.        if (id=(muiNotifyData(obj)->mnd_ObjectID))
  408.        {
  409.           if (data = (ULONG *)DoMethod(msg->dataspace,MUIM_Dataspace_Find,id))
  410.           {
  411.              mydata->myvalue = *data;
  412.           }
  413.        }
  414.  
  415.        return(0);
  416.     }
  417.  
  418.     SEE ALSO
  419.     MUIM_Import, application.mui/MUIM_Application_Load,
  420.     application.mui/MUIM_Application_Save
  421. Notify.mui/MUIM_KillNotify
  422.  
  423.     NAME
  424.     MUIM_KillNotify (V4 )
  425.  
  426.     SYNOPSIS
  427.     DoMethod(obj,MUIM_KillNotify,ULONG TrigAttr);
  428.  
  429.     FUNCTION
  430.     MUIM_KillNotify kills previously given notifications on specific 
  431.     attributes.
  432.  
  433.     INPUTS
  434.     TrigAttr - Attribute for which the notify was specified. If you
  435.                set up more than one notify for an attribute, only
  436.                the first one will be killed.
  437.  
  438.     EXAMPLE
  439.     DoMethod(button,MUIM_KillNotify,MUIA_Pressed);
  440.  
  441.     SEE ALSO
  442.     MUIM_Notify
  443. Notify.mui/MUIM_KillNotifyObj
  444.  
  445.     NAME
  446.     MUIM_KillNotifyObj (V16)
  447.  
  448.     SYNOPSIS
  449.     DoMethod(obj,MUIM_KillNotifyObj,ULONG TrigAttr, Object *dest);
  450.  
  451.     FUNCTION
  452.     yet undocumented, complain in the beta mailing list :)
  453.  
  454.     INPUTS
  455.  
  456.     RESULT
  457.  
  458.     BUGS
  459.  
  460.     SEE ALSO
  461.  
  462. Notify.mui/MUIM_MultiSet
  463.  
  464.     NAME
  465.     MUIM_MultiSet (V7 )
  466.  
  467.     SYNOPSIS
  468.     DoMethod(obj,MUIM_MultiSet,ULONG attr, ULONG val, APTR obj, /* ... */);
  469.  
  470.     FUNCTION
  471.     Set an attribute for multiple objects.
  472.     Receiving an attribute/value pair and a list of objects,
  473.     this method sets the new value for all the objects in the list.
  474.     This is especially useful for disabling/enabling lots of
  475.     objects with one singe function call.
  476.  
  477.     The object that executes this method isn't affected!
  478.  
  479.     Note: This method was implemented in version 7 of notify class.
  480.  
  481.     INPUTS
  482.     attr     attribute to set.
  483.     value    new value for the attribute.
  484.     obj, ... list of MUI objects, terminated with a NULL pointer.
  485.  
  486.     EXAMPLE
  487.     /* disable all the address related gadgets... */
  488.  
  489.     DoMethod(xxx, MUIM_MultiSet, MUIA_Disabled, TRUE,
  490.        ST_Name, ST_Street, ST_City, ST_Country, ST_Phone, NULL);
  491.  
  492.     /* note that the xxx object doesn't get disabled! */
  493.  
  494.     SEE ALSO
  495.     MUIM_Set, MUIM_Notify
  496. Notify.mui/MUIM_NoNotifySet
  497.  
  498.     NAME
  499.     MUIM_NoNotifySet (V9 )
  500.  
  501.     SYNOPSIS
  502.     DoMethod(obj,MUIM_NoNotifySet,ULONG attr, char *format, ULONG val, /* ... */);
  503.  
  504.     FUNCTION
  505.     Acts like MUIM_Set but doesn't trigger any notification.
  506.     This can become useful to avoid deadlocks with bi-directional
  507.     connections.
  508.  
  509.     INPUTS
  510.     attr  attribute you want to set.
  511.     val   value to set the attribute to.
  512.  
  513.     EXMAPLE
  514.     DoMethod(editor,MUIM_Notify,EDIT_Top,MUIV_EveryTime,
  515.        sbar,3,MUIM_NoNotifySet,MUIA_Prop_First,MUIV_TriggerValue);
  516.  
  517.     DoMethod(sbar,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime,
  518.        editor,3,MUIM_NoNotifySet,EDIT_Top,MUIV_TriggerValue);
  519.  
  520.     SEE ALSO
  521.     MUIM_Set
  522. Notify.mui/MUIM_Notify
  523.  
  524.     NAME
  525.     MUIM_Notify (V4 )
  526.  
  527.     SYNOPSIS
  528.     DoMethod(obj,MUIM_Notify,ULONG TrigAttr, ULONG TrigVal, APTR DestObj, ULONG FollowParams, /* ... */);
  529.  
  530.     FUNCTION
  531.     Add a notification event handler to an object. Notification
  532.     is essential for every MUI application.
  533.  
  534.     A notification statement consists of a source object,
  535.     an attribute/value pair, a destination object and a
  536.     notification method. The attribute/value pair belongs
  537.     to the source object and determines when the notification
  538.     method will be executed on the destination object.
  539.  
  540.     Whenever the source object gets the given attribute set to
  541.     the given value (this can happen because of the user
  542.     pressing some gadgets or because of your program explicitly
  543.     setting the attribute with SetAttrs()), the destination
  544.     object will execute the notification method.
  545.  
  546.     With some special values, you can trigger the notification
  547.     every time the attribute is changing. In this case, you
  548.     can include the triggering attributes value within the
  549.     notification method. See below.
  550.  
  551.     One big problem with notification are endless loops.
  552.     Imagine you have a prop gadget and want to show its
  553.     state with a gauge object. You connect MUIA_Prop_First
  554.     with MUIA_Gauge_Max and everything is fine, the gauge
  555.     gets updated when the user drags around the gadget. On
  556.     the other hand, if your program sets the gauge to a new
  557.     value, you might want your prop gadget to immediately
  558.     show this change and connect MUIA_Gauge_Max width
  559.     MUIA_Prop_First. Voila, a perfect endless loop.
  560.  
  561.     To avoid these conditions, MUI always checks new
  562.     attribute values against the current state and
  563.     cancels notification when both values are equal.
  564.     Thus, setting MUIA_Prop_First to 42 if the prop
  565.     gadgets first position is already 42 won't trigger
  566.     any notification event.
  567.  
  568.     INPUTS
  569.     TrigAttr     attribute that triggers the notification.
  570.  
  571.     TrigValue    value that triggers the notification. The
  572.                  special value MUIV_EveryTime makes MUI execute
  573.                  the notification method every time when
  574.                  TrigAttr changes. In this case, the special
  575.                  value MUIV_TriggerValue in the notification
  576.                  method will be replaced with the value
  577.                  that TrigAttr has been set to. You can use
  578.                  MUIV_TriggerValue up to four times in one
  579.                  notification method. Since version 8 of
  580.                  muimaster.library, you can also use
  581.                  MUIV_NotTriggerValue here. In this case,
  582.                  MUI will replace TRUE values with FALSE
  583.                  and FALSE values with TRUE. This
  584.                  can become quite useful when you try to set
  585.                  "negative" attributes like MUIA_Disabled.
  586.  
  587.     DestObj      object on which to perform the notification
  588.                  method. Either supply a valid object pointer or
  589.                  one of the following special values (V10) which
  590.                  will be resolved at the time the event occurs:
  591.                  MUIV_Notify_Self        - notifies the object
  592.                                            itself.
  593.                  MUIV_Notify_Window      - notifies the object's
  594.                                            parent window.
  595.                  MUIV_Notify_Application - notifies the object's
  596.                                            application.
  597.  
  598.     FollowParams number of following parameters. If you e.g.
  599.                  have a notification method with three parts
  600.                  (maybe MUIM_Set,attr,val), you have to set
  601.                  FollowParams to 3. This allows MUI to copy
  602.                  the complete notification method into a
  603.                  private buffer for later use.
  604.  
  605.     ...          following is the notification method.
  606.  
  607.     EXAMPLE
  608.  
  609.     /*
  610.     ** Every time when the user releases a button
  611.     ** (and the mouse is still over it), the button object
  612.     ** gets its MUIA_Pressed attribute set to FALSE.
  613.     ** Thats what a program can react on with notification,
  614.     ** e.g. by openening another window.
  615.     */
  616.  
  617.     DoMethod(buttonobj,MUIM_Notify,
  618.        MUIA_Pressed, FALSE,                /* attribute/value pair */
  619.        windowobj,                          /* destination object   */
  620.        3,                                  /* 3 following words    */
  621.        MUIM_Set, MUIA_Window_Open, TRUE);  /* notification method  */
  622.  
  623.     /*
  624.     ** Lets say we want to show the current value of a
  625.     ** prop gadget somewhere in a text field:
  626.     */
  627.  
  628.     DoMethod(propobj,MUIM_Notify,      /* notification is triggered   */
  629.        MUIA_Prop_First, MUIV_EveryTime /* every time the attr changes */
  630.        textobj                         /* destination object */
  631.        4,                              /* 4 following words  */
  632.        MUIM_SetAsString, MUIA_Text_Contents,
  633.        "value is %ld !", MUIV_TriggerValue);
  634.        /* MUIV_TriggerValue will be replaced with the
  635.           current value of MUIA_Prop_First */
  636.  
  637.     /*
  638.     ** Inform our application when the user hits return
  639.     ** in a string gadget:
  640.     */
  641.  
  642.     DoMethod(stringobj,MUIM_Notify,
  643.        MUIA_String_Acknowledge, MUIV_EveryTime,
  644.        MUIV_Notify_Application, 2, MUIM_Application_ReturnID, ID_FOOBAR);
  645. Notify.mui/MUIM_Set
  646.  
  647.     NAME
  648.     MUIM_Set (V4 )
  649.  
  650.     SYNOPSIS
  651.     DoMethod(obj,MUIM_Set,ULONG attr, ULONG val);
  652.  
  653.     FUNCTION
  654.     Set an attribute to a value. Normally, you would set
  655.     attributes with intuition.library SetAttrs() or with
  656.     the OM_SET method as with any other boopsi objects.
  657.     But since these calls need a complete tag list, not
  658.     just a single attribute/value pair, they are not
  659.     useful within a MUIM_Notify method.
  660.  
  661.     INPUTS
  662.     attr  attribute you want to set.
  663.     val   value to set the attribute to.
  664.  
  665.     EXMAPLE
  666.     DoMethod(strobj,MUIM_Set,MUIA_String_Contents,"foobar");
  667.     and
  668.     SetAttrs(strobj,MUIA_String_Contents,"foobar",TAG_DONE);
  669.     are equal.
  670.  
  671.     SEE ALSO
  672.     MUIM_SetAsString, MUIM_Notify, MUIM_NoNotifySet
  673. Notify.mui/MUIM_SetAsString
  674.  
  675.     NAME
  676.     MUIM_SetAsString (V4 )
  677.  
  678.     SYNOPSIS
  679.     DoMethod(obj,MUIM_SetAsString,ULONG attr, char *format, ULONG val, /* ... */);
  680.  
  681.     FUNCTION
  682.     Set a (text kind) attribute to a string. This can be useful
  683.     if you want to connect a numeric attribute of an object with
  684.     a text attribute of another object.
  685.  
  686.     INPUTS
  687.     attr    attribute to set.
  688.     format  C like formatting string, remember to use "%ld" !
  689.     val,... one or more paremeters for the format string.
  690.  
  691.     EXAMPLE
  692.  
  693.     stand alone:
  694.  
  695.     DoMethod(txobj,MUIM_SetAsString,MUIA_Text_Contents,
  696.              "My name is %s and I am %ld years old.",name,age);
  697.  
  698.     within a notification statement:
  699.  
  700.     DoMethod(propobj,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime,
  701.              txobj,4,MUIM_SetAsString,MUIA_Text_Contents,
  702.              "prop gadget shows %ld.",MUIV_TriggerValue);
  703.  
  704.     SEE ALSO
  705.     MUIM_Set, MUIM_Notify
  706. Notify.mui/MUIM_SetUData
  707.  
  708.     NAME
  709.     MUIM_SetUData (V8 )
  710.  
  711.     SYNOPSIS
  712.     DoMethod(obj,MUIM_SetUData,ULONG udata, ULONG attr, ULONG val);
  713.  
  714.    FUNCTION
  715.     This method tests if the MUIA_UserData of the object
  716.     contains the given <udata> and sets <attr> to
  717.     <val> for itself in this case.
  718.  
  719.     Altough this is not very useful for single objects,
  720.     performing this method on objects that handle children
  721.     can become very handy. In this case, all the children
  722.     (any maybe their children) are tested against <udata>
  723.     and all matching objects will get the attribute set.
  724.  
  725.     If you e.g. want to clear several string gadgets in
  726.     your applciation at once, you simply give them the
  727.     same MUIA_UserData and use
  728.  
  729.     DoMethod(app,MUIM_SetUData,MyUDATA,MUIA_String_Contents,NULL);
  730.  
  731.     INPUTS
  732.     udata - userdata to look for.
  733.     attr  - attribute to set.
  734.     val   - value to set attribute to.
  735.  
  736.     NOTES
  737.     If you have many objects in your application, MUIM_SetUData
  738.     may take quite long. You can limit the amount of time
  739.     by performing the method not on the application but on the
  740.     window or even on the group your gadgets are place in.
  741.  
  742.     SEE ALSO
  743.     MUIM_GetUData, MUIM_FindUData, MUIM_SetUDataOnce
  744. Notify.mui/MUIM_SetUDataOnce
  745.  
  746.     NAME
  747.     MUIM_SetUDataOnce (V11)
  748.  
  749.     SYNOPSIS
  750.     DoMethod(obj,MUIM_SetUDataOnce,ULONG udata, ULONG attr, ULONG val);
  751.  
  752.     FUNCTION
  753.     This method performs like MUIM_SetUData, but stops when it has
  754.     found an object with the given user data. If you don't have
  755.     objects with equal user datas and don't rely on setting all
  756.     of them, MUIM_SetUDataOnce is preferrable because it's more
  757.     efficient.
  758.  
  759.     SEE ALSO
  760.     MUIM_SetUData, MUIM_GetUData
  761.  
  762. Notify.mui/MUIM_WriteLong
  763.  
  764.     NAME
  765.     MUIM_WriteLong (V6 )
  766.  
  767.     SYNOPSIS
  768.     DoMethod(obj,MUIM_WriteLong,ULONG val, ULONG *memory);
  769.  
  770.     FUNCTION
  771.     This method simply writes a longword somewhere to memory.
  772.     Although this seems quite useless, it might become handy
  773.     if used within a notify statement. For instance, you could
  774.     easily connect the current level of a slider with some
  775.     member of your programs data structures.
  776.  
  777.     INPUTS
  778.     val    - value to write
  779.     memory - location to write the value to
  780.  
  781.     EXAMPLE
  782.  
  783.     /* Let the slider automagically write its level to a variable */
  784.  
  785.     static LONG level;
  786.  
  787.     DoMethod(slider,MUIM_Notify,MUIA_Slider_Level,MUIV_EveryTime,
  788.        slider,3,MUIM_WriteLong,MUIV_TriggerValue,&level);
  789.  
  790.     SEE ALSO
  791.     MUIM_WriteString, MUIM_Notify
  792. Notify.mui/MUIM_WriteString
  793.  
  794.     NAME
  795.     MUIM_WriteString (V6 )
  796.  
  797.     SYNOPSIS
  798.     DoMethod(obj,MUIM_WriteString,char *str, char *memory);
  799.  
  800.     FUNCTION
  801.     This method simply copies a string somewhere to memory.
  802.     Although this seems quite useless, it might become handy
  803.     if used within a notify statement. For instance, you could
  804.     easily connect the current contents of a string gadget
  805.     with some member of your programs data structures.
  806.  
  807.     Note: The string is copied with strcpy(), you must assure
  808.               that the destination points to enough memory.
  809.  
  810.     INPUTS
  811.     str    - string to copy
  812.     memory - location to write the value to
  813.  
  814.     EXAMPLE
  815.  
  816.     static char buffer[256];
  817.  
  818.     DoMethod(string,MUIM_Notify,MUIA_String_Contents,MUIV_EveryTime,
  819.        string,3,MUIM_WriteString,MUIV_TriggerValue,buffer);
  820.  
  821.     SEE ALSO
  822.     MUIM_WriteLong, MUIM_Notify
  823.